
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Bent Plume Model User’s Guide &#8212; Texas A&amp;M Oil spill / Outfall Calculator 2.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="bpm_blowout_sim" href="../scripts/bpm/bpm_blowout_sim.html" />
    <link rel="prev" title="sbm_file_io" href="../scripts/spm/spm_file_io.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="bent-plume-model-user-s-guide">
<h1>Bent Plume Model User’s Guide<a class="headerlink" href="#bent-plume-model-user-s-guide" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Release</dt>
<dd class="field-odd"><p>2.1</p>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jun 05, 2020</p>
</dd>
</dl>
<div class="section" id="scripts">
<h2>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
<p>The class objects and method functions defined in the <cite>bent_plume_model</cite>
module provide a flexible structure to handle simulations of a multiphase
plume from a discrete source in a flowing ambient environment. The examples
detailed below show how to set up and run <cite>bent_plume_model</cite>
simulations. Further examples are presented in the following scripts
distributed in the <code class="docutils literal notranslate"><span class="pre">./bin/bpm</span></code> directory with the source code.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../scripts/bpm/bpm_blowout_sim.html">bpm_blowout_sim</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/bpm/crossflow_plume.html">crossflow_plume</a></li>
</ul>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>This example illustrates the tasks necessary to setup, run, save, and
post-process simulations using the <cite>bent_plume_model</cite> module. Before
running these examples, be sure to install the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> package and run
all of the tests in the <code class="docutils literal notranslate"><span class="pre">./test</span></code> directory.  The commands below should
be executed in an IPython session.  Start IPython by executing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ipython</span> <span class="o">--</span><span class="n">pylab</span>
</pre></div>
</div>
<p>at the command prompt.  The <code class="docutils literal notranslate"><span class="pre">--pylab</span></code> flag is needed to get the correct
behavior of the output plots.</p>
<p>The first step in any spill simulation is to define the ambient CTD data. The
<code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> module <cite>ambient</cite> provides the tools needed to read in CTD data from
text files and organize it into the netCDF files used by the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code>
simulation modules. Examples of how to do this are provided in the
<code class="docutils literal notranslate"><span class="pre">./bin/ambient</span></code> directory of the TAMOC distribution. Here, we use the CTD
data created by the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> test files and stored in the <code class="docutils literal notranslate"><span class="pre">./test/output</span></code>
directory. Open a CTD file as follows (path names in this tutorial are from
any subdirectory of the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> source distribution, e.g.,
<code class="docutils literal notranslate"><span class="pre">./notebooks</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_file</span> <span class="o">=</span> <span class="s1">&#39;../test/output/test_BM54.nc&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="n">ctd_file</span><span class="p">,</span> <span class="n">chem_names</span><span class="o">=</span><span class="s1">&#39;all&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Once the CTD data are loaded as an <cite>ambient.Profile</cite> object, a
<cite>bent_bubble_model</cite> object can be initialized:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span> <span class="o">=</span> <span class="n">bent_plume_model</span><span class="o">.</span><span class="n">Model</span><span class="p">(</span><span class="n">ctd</span><span class="p">)</span>
</pre></div>
</div>
<p>The initial conditions for the release include the depth and discharge
characteristics.  A few are universal to the simulation and should be
specified right away:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x0</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">,</span> <span class="mf">1000.</span><span class="p">])</span>   <span class="c1"># release location (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">D</span> <span class="o">=</span> <span class="mf">0.30</span>                         <span class="c1"># diameter of release region (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vj</span> <span class="o">=</span> <span class="mf">0.</span>                          <span class="c1"># 0 for multiphase plume</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">phi_0</span> <span class="o">=</span> <span class="o">-</span><span class="n">np</span><span class="o">.</span><span class="n">pi</span> <span class="o">/</span> <span class="mi">2</span>               <span class="c1"># vertical release</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">theta_0</span> <span class="o">=</span> <span class="mf">0.</span>                     <span class="c1"># angle to x-axis</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Sj</span> <span class="o">=</span> <span class="mf">0.</span>                          <span class="c1"># salinity of jet (psu)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Tj</span> <span class="o">=</span> <span class="mf">273.15</span> <span class="o">+</span> <span class="mf">30.</span>                <span class="c1"># temperature of jet (K)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cj</span> <span class="o">=</span> <span class="mf">1.</span>                          <span class="c1"># concentration of passive tracers</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tracers</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;tracers&#39;</span><span class="p">]</span>            <span class="c1"># tracer names</span>
</pre></div>
</div>
<p>The remaining initial conditions are the dispersed phases that make up the
plume. These should be passed to the <cite>bent_plume_model.Model</cite> object as a list
of <cite>bent_plume_model.Particle</cite> objects. First, open an empty list, then create
<cite>bent_plume_model.Particle</cite> objects and append them to the list.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">particles</span> <span class="o">=</span> <span class="p">[]</span>
</pre></div>
</div>
<div class="section" id="gas-bubbles">
<h3>Gas Bubbles<a class="headerlink" href="#gas-bubbles" title="Permalink to this headline">¶</a></h3>
<p>For a blowout, we might expect both gas and oil.  Here, we create a few
gas bubbles to add to the simulation.  The first step is to create a <cite>dbm</cite>
particle object.  In this case, we choose a dissolvable particle of natural
gas:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">composition</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;methane&#39;</span><span class="p">,</span> <span class="s1">&#39;ethane&#39;</span><span class="p">,</span> <span class="s1">&#39;propane&#39;</span><span class="p">,</span> <span class="s1">&#39;oxygen&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mol_frac</span> <span class="o">=</span> <span class="p">[</span><span class="mf">0.93</span><span class="p">,</span> <span class="mf">0.05</span><span class="p">,</span> <span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gas</span> <span class="o">=</span> <span class="n">dbm</span><span class="o">.</span><span class="n">FluidParticle</span><span class="p">(</span><span class="n">composition</span><span class="p">)</span>
</pre></div>
</div>
<p>Next, we have to get the mass of each component in a single bubble and the
total bubble flux. A helper function is provided in the <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> model called
<cite>dispersed_phases.initial_conditions</cite>. Here, we use the function to create six
different sized bubbles:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># Initial bubble diameter (m)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">de</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.04</span><span class="p">,</span> <span class="mf">0.03</span><span class="p">,</span> <span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">,</span> <span class="mf">0.0075</span><span class="p">,</span> <span class="mf">0.005</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Total mass flux (kg/s) of gas in each bubble size class</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m0</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">3.5</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">]</span> <span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Associate spreading ratio (--)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lambda_1</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.75</span><span class="p">,</span> <span class="mf">0.8</span><span class="p">,</span> <span class="mf">0.85</span><span class="p">,</span> <span class="mf">0.9</span><span class="p">,</span> <span class="mf">0.9</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Append to the disp_phases list</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">de</span><span class="p">)):</span>
<span class="go">        m, T, nb, P, Sa, Ta = dispersed_phases.initial_conditions(</span>
<span class="go">            ctd, x0[2], gas, mol_frac, m0[i], 2, de[i], Tj)</span>
<span class="go">        particles.append(bent_plume_model.Particle(x0[0], x0[1], x0[2],</span>
<span class="go">            gas, m, T, nb, lambda_1[i], P, Sa, Ta))</span>
</pre></div>
</div>
</div>
<div class="section" id="oil-droplets">
<h3>Oil Droplets<a class="headerlink" href="#oil-droplets" title="Permalink to this headline">¶</a></h3>
<p>Following the same procedure as for the gas but with different equations of
state, liquid droplets can be added to the simulation. Start, by defining a
new set of equations of state. Here, we assume a non-dissolving oil phase:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">composition</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;inert&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rho_o</span> <span class="o">=</span> <span class="mf">890.</span>     <span class="c1"># density in kg/m^3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gamma</span> <span class="o">=</span> <span class="mf">30.</span>      <span class="c1"># API gravity in deg API</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">beta</span> <span class="o">=</span> <span class="mf">0.0007</span>    <span class="c1"># thermal expansion coefficient in K^(-1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">co</span> <span class="o">=</span> <span class="mf">2.90075e-9</span>  <span class="c1"># isothermal compressibility coefficient in Pa^(-1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">oil</span> <span class="o">=</span> <span class="n">dbm</span><span class="o">.</span><span class="n">InsolubleParticle</span><span class="p">(</span><span class="kc">True</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="n">rho_o</span><span class="p">,</span> <span class="n">gamma</span><span class="p">,</span> <span class="n">beta</span><span class="p">,</span> <span class="n">co</span><span class="p">)</span>
</pre></div>
</div>
<p>Then, define the droplet characteristics and append them to the
<code class="docutils literal notranslate"><span class="pre">particles</span></code> list as we did for the gas bubbles. Note that all particles go
in the same list and could be in any order:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">de</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.02</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">,</span> <span class="mf">0.0075</span><span class="p">,</span> <span class="mf">0.005</span><span class="p">,</span> <span class="mf">0.003</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m0</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">5.</span><span class="p">,</span> <span class="mf">1.</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lambda_1</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.85</span><span class="p">,</span> <span class="mf">0.90</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">,</span> <span class="mf">1.</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">de</span><span class="p">)):</span>
<span class="go">        m, T, nb, P, Sa, Ta = dispersed_phases.initial_conditions(</span>
<span class="go">            ctd, x0[2], oil, 1., m0[i], 2, de[i], Tj)</span>
<span class="go">        particles.append(bent_plume_model.Particle(x0[0], x0[1], x0[2],</span>
<span class="go">            oil, m, T, nb, lambda_1[i], P, Sa, Ta))</span>
</pre></div>
</div>
</div>
<div class="section" id="run-the-simulation">
<h3>Run the Simulation<a class="headerlink" href="#run-the-simulation" title="Permalink to this headline">¶</a></h3>
<p>At this point, all of the initial conditions are defined, and we can run
the simulation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">dt_max</span> <span class="o">=</span> <span class="mf">60.</span>     <span class="c1"># maximum time step to take for output (s)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sd_max</span> <span class="o">=</span> <span class="mf">450.</span>    <span class="c1"># maximum number of nozzle diameters to integrate</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span><span class="o">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">x0</span><span class="p">,</span> <span class="n">D</span><span class="p">,</span> <span class="n">Vj</span><span class="p">,</span> <span class="n">phi_0</span><span class="p">,</span> <span class="n">theta_0</span><span class="p">,</span> <span class="n">Sj</span><span class="p">,</span> <span class="n">Tj</span><span class="p">,</span> <span class="n">cj</span><span class="p">,</span> <span class="n">tracers</span><span class="p">,</span>
<span class="go">                 particles, False, dt_max, sd_max)</span>
</pre></div>
</div>
<p>The above command will echo progress to the screen</p>
</div>
<div class="section" id="plotting-the-model-results">
<h3>Plotting the Model Results<a class="headerlink" href="#plotting-the-model-results" title="Permalink to this headline">¶</a></h3>
<p>Two different methods are provided to plot the data.  To get a quick view of
the model trajectory and mass of the Lagrangian element during the simulation,
use the plot state space method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span><span class="o">.</span><span class="n">plot_state_space</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
<p>To see a more comprehensive array of model output, use the plot all variables
method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span><span class="o">.</span><span class="n">plot_all_variables</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="saving-model-results">
<h3>Saving Model Results<a class="headerlink" href="#saving-model-results" title="Permalink to this headline">¶</a></h3>
<p>The simulation results can be saved to a netCDF file, which can be used to
continue analysis within the TAMOC Python package, or an ascii text file for
importing to another analysis package, such as Excel or Matlab. To save the
data, specify a base output name with relative file path, a path to the CTD
data, and a description of the CTD data:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f_name</span> <span class="o">=</span> <span class="s1">&#39;../test/output/test_blowout&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_description</span> <span class="o">=</span> <span class="s1">&#39;CTD data from Brooks McCall in file&#39;</span> <span class="o">+</span> \
<span class="go">                      &#39;./test/output/test_BM54.nc&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span><span class="o">.</span><span class="n">save_sim</span><span class="p">(</span><span class="n">f_name</span> <span class="o">+</span> <span class="s1">&#39;.nc&#39;</span><span class="p">,</span> <span class="n">ctd_file</span><span class="p">,</span> <span class="n">ctd_description</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bpm</span><span class="o">.</span><span class="n">save_txt</span><span class="p">(</span><span class="n">f_name</span> <span class="o">+</span> <span class="s1">&#39;ASCII&#39;</span><span class="p">,</span> <span class="n">ctd_file</span><span class="p">,</span> <span class="n">ctd_description</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Texas A&M Oil spill / Outfall Calculator</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../user_manual.html">TAMOC User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../unit_tests.html">Unit Tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../readme.html">Read Me File</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
  <li><a href="../user_manual.html">TAMOC User Manual</a><ul>
      <li>Previous: <a href="../scripts/spm/spm_file_io.html" title="previous chapter">sbm_file_io</a></li>
      <li>Next: <a href="../scripts/bpm/bpm_blowout_sim.html" title="next chapter">bpm_blowout_sim</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, Scott A. Socolofsky.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="../_sources/guides/bpm.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>